package org.nnxy.foodboot.service;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 数据统计服务接口
 * 提供食谱统计、用户交互统计、热门排行等数据查询功能
 */
public interface StatisticsService {
    
    /**
     * 获取食谱相关统计数据
     * 包括：食谱总数、分类分布、时间趋势等
     * 
     * @return 统计结果，包含以下字段：
     *         - totalCount: 食谱总数
     *         - flavorDistribution: 口味分布
     *         - techniqueDistribution: 技巧分布
     *         - difficultyDistribution: 难度分布
     *         - categoryDistribution: 分类分布
     *         - trendData: 时间趋势数据
     */
    Map<String, Object> getRecipeStatistics();
    
    /**
     * 获取用户交互相关统计数据
     * 包括：浏览量、收藏量、推荐点击量、时间趋势等
     * 
     * @param days 统计的天数，默认30天
     * @return 统计结果，包含以下字段：
     *         - overview: 总览数据，包含browseCount、favoriteCount、recommendClickCount
     *         - browseTrend: 浏览趋势
     *         - favoriteTrend: 收藏趋势
     *         - recommendationTrend: 推荐点击率趋势
     */
    Map<String, Object> getInteractionStatistics(Integer days);
    
    /**
     * 获取热门食谱排行数据
     * 包括：浏览量最高、收藏最多、评分最高的食谱
     * 
     * @param limit 每项排行的显示数量，默认10
     * @return 统计结果，包含以下字段：
     *         - mostViewed: 浏览量最高的食谱
     *         - mostFavorited: 收藏最多的食谱
     *         - highestRated: 评分最高的食谱
     */
    Map<String, Object> getPopularRecipes(Integer limit);
    
    /**
     * 获取最近添加的食谱列表
     * 
     * @param limit 限制数量，默认10
     * @return 最近添加的食谱列表
     */
    List<Map<String, Object>> getRecentAddedRecipes(Integer limit);
    
    /**
     * 获取食谱详情
     * 包括食谱基本信息和统计数据（浏览量、收藏量、评分等）
     * 
     * @param recipeId 食谱ID
     * @return 食谱详情
     */
    Map<String, Object> getRecipeDetailWithStats(Long recipeId);
    
    /**
     * 获取按月统计的食谱创建数量
     * 
     * @param year 年份，默认当前年
     * @return 月度统计数据
     */
    List<Map<String, Object>> getRecipeStatsByMonth(Integer year);
    
    /**
     * 统计各口味食谱数量
     * 
     * @return 口味-数量映射，key为口味名称，value为数量
     */
    Map<String, Long> countByFlavor();
    
    /**
     * 统计各制作技巧食谱数量
     * 
     * @return 技巧-数量映射，key为技巧名称，value为数量
     */
    Map<String, Long> countByTechnique();
    
    /**
     * 统计各难度等级食谱数量
     * 
     * @return 难度-数量映射，key为难度等级，value为数量
     */
    Map<String, Long> countByDifficulty();
    
    /**
     * 统计各分类的食谱数量
     * 
     * @return 分类-数量映射，key为分类名称，value为数量
     */
    Map<String, Long> countByCategory();
    
    /**
     * 统计指定时间范围内的食谱数量
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 时间范围内的食谱数量
     */
    long countRecipesByTimeRange(LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 统计指定时间范围内的浏览数量
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 时间范围内的浏览数量
     */
    long countBrowseByTimeRange(LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 统计指定时间范围内的收藏数量
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 时间范围内的收藏数量
     */
    long countFavoriteByTimeRange(LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 统计指定时间范围内的推荐记录数量
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 时间范围内的推荐记录数量
     */
    long countRecommendationByTimeRange(LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 统计指定时间范围内的推荐点击数量
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 时间范围内的推荐点击数量
     */
    long countRecommendationClicksByTimeRange(LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 获取浏览量最高的食谱
     * 
     * @param limit 限制数量
     * @return 食谱列表，每个食谱包含id、name、image_url、view_count等字段
     */
    List<Map<String, Object>> getMostViewedRecipes(Integer limit);
    
    /**
     * 获取收藏最多的食谱
     * 
     * @param limit 限制数量
     * @return 食谱列表，每个食谱包含id、name、image_url、favorite_count等字段
     */
    List<Map<String, Object>> getMostFavoritedRecipes(Integer limit);
    
    /**
     * 获取评分最高的食谱
     * 
     * @param limit 限制数量
     * @return 食谱列表，每个食谱包含id、name、image_url、avg_rating、rating_count等字段
     */
    List<Map<String, Object>> getHighestRatedRecipes(Integer limit);
    
    /**
     * 获取浏览趋势数据
     * 
     * @param days 统计天数
     * @return 每日趋势数据列表，每条数据包含date(日期)、count(浏览数)字段
     */
    List<Map<String, Object>> getBrowseTrend(int days);
    
    /**
     * 获取收藏趋势数据
     * 
     * @param days 统计天数
     * @return 每日趋势数据列表，每条数据包含date(日期)、count(收藏数)字段
     */
    List<Map<String, Object>> getFavoriteTrend(int days);
    
    /**
     * 获取推荐点击率趋势数据
     * 
     * @param days 统计天数
     * @return 每日趋势数据列表，每条数据包含date(日期)、rate(点击率)、total(总展示数)、clicked(点击数)字段
     */
    List<Map<String, Object>> getRecommendationClickRateTrend(int days);
    
    /**
     * 获取自定义时间范围内的统计数据
     * 
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @param type 统计类型，可选值：browse, favorite, recommendation, all
     * @return 指定时间范围的统计数据，包含不同类型的统计结果
     */
    Map<String, Object> getCustomRangeStats(java.time.LocalDate startDate, java.time.LocalDate endDate, String type);
} 